home *** CD-ROM | disk | FTP | other *** search
/ SGI Performance Co-Pilot 1.3 / SGI Performance Co-Pilot 1.3.iso / dist / pcp.idb / usr / share / catman / u_man / cat1 / pmrules.z / pmrules
Text File  |  1997-04-03  |  16KB  |  265 lines
  1.  
  2.  
  3.  
  4. PPPPMMMMRRRRUUUULLLLEEEESSSS((((1111))))                                                          PPPPMMMMRRRRUUUULLLLEEEESSSS((((1111))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ppppmmmmrrrruuuulllleeeessss - Performance Co-Pilot editor for ppppmmmmiiiieeee rule templates
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ppppmmmmrrrruuuulllleeeessss [_f_i_l_e [_i_m_p_o_r_t_f_i_l_e] ]
  13.  
  14. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  15.      ppppmmmmrrrruuuulllleeeessss provides a graphical user interface for instantiating and editing
  16.      rules for ppppmmmmiiiieeee(1) (the Performance Co-Pilot Inference Engine) without
  17.      having to learn the ppppmmmmiiiieeee(1) syntax.
  18.  
  19.      ppppmmmmrrrruuuulllleeeessss cannot be used to create new ppppmmmmiiiieeee rules.  Rather, it allows one
  20.      to edit existing rules that have been specified using templates.  A
  21.      template is like a rule but with certain elements of the rule
  22.      parameterized.  These parameters are the parts of the rule that a ppppmmmmrrrruuuulllleeeessss
  23.      user may change.
  24.  
  25.      For example, a ppppmmmmiiiieeee rule to raise an alarm if a machine becomes too busy
  26.      may include a comparison of the CPU idle time with one threshold and the
  27.      disk throughput rate with another threshold.  The two thresholds are
  28.      specified as fixed numbers in the rule.  If this rule is described by a
  29.      template, the two thresholds are specified as parameters (with variable
  30.      values).  Each template also has an enable/disable state.  When ppppmmmmrrrruuuulllleeeessss
  31.      is used to edit the template, only the thresholds, the template's name
  32.      and the enable/disable state may be changed, the rest is immutable.
  33.  
  34.      ppppmmmmrrrruuuulllleeeessss is usually started with a _f_i_l_e of templates to be edited as its
  35.      sole command line argument.  A list of the templates from the file
  36.      appears in the main window.  This is the active set of templates.  The
  37.      operations available through the menus apply only to the active set.
  38.  
  39.      Saving the active set also generates a file containing the corresponding
  40.      ppppmmmmiiiieeee rules.  That file will have the same name as the saved template
  41.      file, with ....ppppmmmmiiiieeee appended.  During the save operation, any template
  42.      marked ``disable'' will not generate any corresponding ppppmmmmiiiieeee rules.
  43.  
  44.      For convenience we use the notation MMMMyyyymmmmeeeennnnuuuu->IIIItttteeeemmmm to indicate that IIIItttteeeemmmm
  45.      should be chosen from the MMMMyyyymmmmeeeennnnuuuu menu.  For example TTTTeeeemmmmppppllllaaaatttteeee->DDDDeeeelllleeeetttteeee
  46.      indicates that the DDDDeeeelllleeeetttteeee item should be chosen from the TTTTeeeemmmmppppllllaaaatttteeee menu.
  47.  
  48.      Items from the FFFFiiiilllleeee menu apply to the entire active set.  Only one file
  49.      of templates may be open for editing at a time.  Thus it is necessary to
  50.      FFFFiiiilllleeee->CCCClllloooosssseeee the active set before opening another templates file.
  51.  
  52.      New templates may be added to the active set by either copying existing
  53.      ones or by importing them from files.
  54.  
  55.      To copy an existing template, select it by clicking on it and choose
  56.      TTTTeeeemmmmppppllllaaaatttteeee->CCCCooooppppyyyy.  The copy is added to the bottom of the active set.  Its
  57.      name is the name of the original template, with ccccooooppppyyyy ooooffff prepended.
  58.      Similarly, to delete a template from the active set, select it and choose
  59.      TTTTeeeemmmmppppllllaaaatttteeee->DDDDeeeelllleeeetttteeee.
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. PPPPMMMMRRRRUUUULLLLEEEESSSS((((1111))))                                                          PPPPMMMMRRRRUUUULLLLEEEESSSS((((1111))))
  71.  
  72.  
  73.  
  74.      To import a template from another file of templates into the active set,
  75.      choose TTTTeeeemmmmppppllllaaaatttteeee->IIIImmmmppppoooorrrrtttt.............  This brings up the Import Template dialog
  76.      box.  The CCCChhhhoooooooosssseeee FFFFiiiilllleeee............ button at the bottom allows one to open a file.
  77.      Once a file has been opened a list of the templates in the file will
  78.      appear in the scrolled list that dominates the dialog.  Select the
  79.      template(s) to be copied to the active set and click on OOOOKKKK.  The CCCCaaaannnncccceeeellll
  80.      button aborts the import operation.
  81.  
  82.      To edit a template's parameters, actions, enable/disable it, change its
  83.      name or read information about the template, select the template in the
  84.      main window and choose TTTTeeeemmmmppppllllaaaatttteeee->EEEEddddiiiitttt.............  Double clicking on the
  85.      template in the main window has the same effect.  This brings up the Edit
  86.      Template dialog box.  At the top is a text field where the name of the
  87.      template may be changed.  A toggle button on the right allows the
  88.      template to be enabled or disabled.  This determines whether ppppmmmmiiiieeee will
  89.      ignore the rule or not.  Below this is some text, labelled HHHHeeeellllpppp,
  90.      describing the template and it's parameters.  Below the help text is a
  91.      series of labelled text fields displaying values for the template's
  92.      parameters.
  93.  
  94.      A series of predefined actions appears near the bottom of the dialog box.
  95.      Each is preceded by a check box allowing the action to be enabled or
  96.      diabled.  When ppppmmmmiiiieeee is run using the rules generated from the template
  97.      and a rule condition is satisfied, the actions that are enabled will be
  98.      executed.  Actions may include references to the rule's parameters and
  99.      global parameters.  References to parameters in actions are shown in a
  100.      bold typeface.
  101.  
  102.      Rules often supply a special action named uuuusssseeeerrrr aaaaccccttttiiiioooonnnn which has an
  103.      associated parameter with the same name.  If that action is enabled, the
  104.      associated parameter will be executed as a shell command by ppppmmmmiiiieeee when the
  105.      rule fires.  This allows arbitrary actions to be executed in addition to
  106.      the predefined ones.  Two special (hidden) parameters named rrrruuuulllleeee and hhhhoooosssstttt
  107.      are defined for actions.  These are the name of the rule that caused the
  108.      action and the host for which the condition is true respectively.  They
  109.      are not available in a uuuusssseeeerrrr aaaaccccttttiiiioooonnnn.
  110.  
  111.      New values may be typed into the fields to change the values of the
  112.      parameters.  If Enter is pressed after the new value is entered, the new
  113.      value will be checked; if it is invalid a warning dialog will be posted.
  114.      The Tab or BackTab keys may be used to move through the parameters.  If a
  115.      parameter has an invalid value, Tab (BackTab) will not move to the next
  116.      (previous) parameter.  Pressing Return at that point will yield a message
  117.      as to why the parameter's value is inappropriate.
  118.  
  119.      The DDDDeeeeffffaaaauuuullllttttssss button at the bottom of the Edit Template dialog box
  120.      restores the values of all parameters to some default values predefined
  121.      when the template was first created.  Note that these are not necessarily
  122.      the values the parameters had prior to bringing up the dialog box. They
  123.      are not even guaranteed to be the values that the parameters had when the
  124.      templates file was opened.  They are fallback values determined by the
  125.      template's creator.
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. PPPPMMMMRRRRUUUULLLLEEEESSSS((((1111))))                                                          PPPPMMMMRRRRUUUULLLLEEEESSSS((((1111))))
  137.  
  138.  
  139.  
  140.      The OOOOKKKK button updates the parameter values and dismisses the Edit
  141.      Template dialog box.  If one or more parameters have invalid values, when
  142.      the OOOOKKKK button is pressed, an error dialog will appear, listing the
  143.      parameters in error.  This dialog may be dismissed or moved to the side
  144.      while the offending values are corrected.
  145.  
  146.      The NNNNeeeexxxxtttt and PPPPrrrreeeevvvviiiioooouuuussss buttons provide an easy way to edit the next and
  147.      previous templates in the main window.  Using either of these buttons is
  148.      the same as pressing the OOOOKKKK button, selecting the adjacent template in
  149.      the main window and then selecting TTTTeeeemmmmppppllllaaaatttteeee->EEEEddddiiiitttt.............  Any changes made
  150.      to the template currently being edited are accepted.  An error dialog
  151.      describing the problem(s) will appear if there are invalid values for any
  152.      of the parameters in the current template.  It isn't possible to move to
  153.      the adjacent templates until the values are correct.
  154.  
  155.      The CCCCaaaannnncccceeeellll button discards any changes that were made in the Edit
  156.      Template dialog and dismisses it.
  157.  
  158.      Templates may share parameters.  Such parameters are said to be global.
  159.      Choosing TTTTeeeemmmmppppllllaaaatttteeee->EEEEddddiiiitttt GGGGlllloooobbbbaaaallllssss............ brings up the Edit Global Parameters
  160.      dialog box.  Its appearance and behavior are almost identical to the Edit
  161.      Template dialog box.
  162.  
  163.      When a new template is imported into the active set, it brings any global
  164.      parameters it requires with it if they do not already exist.  The
  165.      definition of a parameter in a template takes precedence over an
  166.      identically named global parameter.  Including a new template in the
  167.      active set that uses a global parameter with the same name as template-
  168.      specific parameters defined in existing templates will not affect the
  169.      existing templates.
  170.  
  171.      The OOOOppppttttiiiioooonnnnssss menu contains two items.  SSSShhhhoooowwww rrrruuuulllleeee ccccoooonnnnddddiiiittttiiiioooonnnnssss displays the
  172.      condition associated with the ppppmmmmiiiieeee rule that a template describes when
  173.      the template is being edited; this condition is displayed using the ppppmmmmiiiieeee
  174.      syntax.  SSSShhhhoooowwww gggglllloooobbbbaaaallllssss iiiinnnn rrrruuuulllleeee hhhheeeellllpppp includes global parameters in the help
  175.      text displayed when templates are being edited.  All global parameters
  176.      are displayed, not just the ones the rule uses.
  177.  
  178.      If ppppmmmmrrrruuuulllleeeessss is started with no arguments, the active set is empty and
  179.      either an active set must be loaded (FFFFiiiilllleeee->OOOOppppeeeennnn............) or a new active set
  180.      started (TTTTeeeemmmmppppllllaaaatttteeee->IIIImmmmppppoooorrrrtttt............).  If _i_m_p_o_r_t_f_i_l_e is specified on the command
  181.      line it is expected to be a template file which will be pre-loaded into
  182.      the list in the Import Template dialog box.  The _f_i_l_e argument may be ----,
  183.      which specifies that no templates are to be loaded into the active set
  184.      for editing.  This is usually done when an _i_m_p_o_r_t_f_i_l_e is also supplied.
  185.  
  186. FFFFIIIILLLLEEEESSSS
  187.      ////vvvvaaaarrrr////ppppccccpppp////ccccoooonnnnffffiiiigggg////ppppmmmmrrrruuuulllleeeessss////*
  188.                              template files supplied with the Performance Co-
  189.                              Pilot (PCP) and its various add-on products.
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. PPPPMMMMRRRRUUUULLLLEEEESSSS((((1111))))                                                          PPPPMMMMRRRRUUUULLLLEEEESSSS((((1111))))
  203.  
  204.  
  205.  
  206.      ////vvvvaaaarrrr////ppppccccpppp////ccccoooonnnnffffiiiigggg////ppppmmmmiiiieeee////ccccoooonnnnttttrrrroooollll
  207.                              control over concurrent execution limits for
  208.                              standard ppppmmmmiiiieeee action scripts
  209.      ////vvvvaaaarrrr////ppppccccpppp////ccccoooonnnnffffiiiigggg////ppppmmmmiiiieeee////*  standard ppppmmmmiiiieeee action scripts
  210.      ////uuuussssrrrr////ppppccccpppp////lllliiiibbbb////ppppmmmmiiiieeee----ccccoooommmmmmmmoooonnnn
  211.                              common shell procedures used by the standard ppppmmmmiiiieeee
  212.                              action scripts
  213.      ////uuuussssrrrr////lllliiiibbbb////XXXX11111111////aaaapppppppp----ddddeeeeffffaaaauuuullllttttssss////PPPPmmmmRRRRuuuulllleeeessss
  214.                              X11 application default resources.
  215.  
  216. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  217.      ppppmmmmiiiieeee(1) and ppppmmmmrrrruuuulllleeeessss(4).
  218.  
  219. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  220.      Various self-explanatory messages appear in dialogs.
  221.  
  222. BBBBUUUUGGGGSSSS
  223.      The treatment of the hidden global parameter hhhhoooosssstttt may cause some
  224.      surprises.  The generated ppppmmmmiiiieeee rules are enumerated for each host, which
  225.      effectively over-rides any use of the default host by ppppmmmmiiiieeee at run-time -
  226.      and in particular this means the ----hhhh option for ppppmmmmiiiieeee will have no effect.
  227.      As a special case, for the global parameter hhhhoooosssstttt, a hostname of llllooooccccaaaallllhhhhoooosssstttt
  228.      (and this is the default) is suppressed in the predicate part of the
  229.      generated ppppmmmmiiiieeee rules, and is replaced by the literal _d_e_f_a_u_l_t-_p_m_i_e-_h_o_s_t in
  230.      the parameters for the actions.  This means the metrics will be fetched
  231.      from the default host, but it is not possible to identify the host in the
  232.      actions.
  233.  
  234.      This special handling reduces, but does not eliminate, user surprise.
  235.      The preferred way to specify remote hosts in rules generated by ppppmmmmrrrruuuulllleeeessss
  236.      is to set the global parameter hhhhoooosssstttt to the desired hostname, save the
  237.      rules, and then use ppppmmmmiiiieeee without the ----hhhh option.
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.